This file documents all the changes made to SpriteWorld since version 2.1 was released. Many things were changed that will affect you as a user. If you were previously using a version of SpriteWorld prior to version 2.2, it is important that you read through all the changes that have been made since the version you are using was released, and make changes to your source code where necessary. You will only have to do this once, and then will be able to take advantage of the new features in the current version. You should also print out the new versions of the documentation. (Inside SpriteWorld, SpriteWorld - Scrolling, SpriteWorld - Tiling, etc.)
Changes in 2.2.1
• Modified SWCollideSpriteLayer and SWCollideCircularSpriteLayer so it is now safe to call SWRemoveSpriteFromAnimation (but not SWRemoveSprite) to remove as many Sprites as you want from any SpriteLayer from within your collideProc. Note that it is still unsafe to do this from a MoveProc or FrameProc. For those routines, it is only safe to remove the srcSpriteP that is passed to that function, or Sprites from Layers other than the one the srcSpriteP is in. But your collideProc may remove any Sprite(s) it wishes without any problems.
• Fixed a bug where SWCreateRegionFromGWorldAndRect wouldn't work correctly. This bug wouldn't have affected you unless you called this function directly, or called BlitPixie8BitFlipSprite on a Sprite with a maskRgn.
SpriteWorld 2.2.1 is a minor update to 2.2. The flexibility that was added to SWCollideSpriteLayer was considered important enough to warrant this update, even though little else has changed since 2.2.
Changes in 2.2
Tiling Changes:
• IMPORTANT! The name of the function SWSetTileMaskDrawProc was changed to SWSetPartialMaskDrawProc. However, if you forget to change your code, you won't get any compiler errors, because a new function called SWSetTileMaskDrawProc was added. This function is different from the old SWSetTileMaskDrawProc, so it is important that you change the name! To help ensure that you remember to do so, the new SWSetTileMaskDrawProc function will return an error code if you try to install either BlitPixie8BitPartialMaskDrawProc or BP8BitInterlacedPartialMaskDrawProc as its DrawProc, since this function is now for normal mask DrawProcs, not partialMask drawProcs. But you have to check for an error code for this to be of any help! I recommend doing a Find & Replace through all your source code to change all occurrences of SWSetTileMaskDrawProc to SWSetPartialMaskDrawProc.
• Added two functions to allow you to use multiple tile layers (where all layers are the same size and scroll the same speed): SWSetNumActiveTileLayers, and SWSetSpriteLayerUnderTileLayer.
• Added several new functions for adding a picture or pattern behind your tiles: SWCreateExtraBackFrame, SWDisposeExtraBackFrame, SWSetPortToExtraBackFrame.
• SWInstallTileMap, SWDrawTile, SWReturnTileUnderPixel, and SWCheckSpriteWithTiles have all had tileLayer parameters added to them, so they know which tile layer you are operating on.
• SWSetSpriteUnderTiles has been removed, since its functionality has been replaced by SWSetSpriteLayerUnderTileLayer.
• Due to the changes necessary to allow you to use multiple tile layers, if you previously accessed the spriteWorldP->tileMapStructP variable, you must now use spriteWorldP->tileLayerArray[tileLayer] instead, where tileLayer is a number between 0 and 9 specifying the tile layer of the TileMap you wish to read.
SpriteLayer Changes:
• SWRemoveSprite, SWSwapSprite, SWInsertSpriteBeforeSprite, and SWInsertSpriteAfterSprite have all had their spriteLayer parameters removed. This is because each Sprite now keeps track of the layer it is currently in. In addition, SWSwapSprite now return an error code if the Sprites being swapped are not both in the same layer, SWRemoveSprite returns an error code if the Sprite isn't part of any layer, and SWAddSprite, SWInsertSpriteBeforeSprite, and SWInsertSpriteAfterSprite return error codes if the Sprite is already part of a Layer.
Misc Changes:
• Totally rebuilt the circular scrolling engine to do what I previously thought impossible - it now allows you to make the offscreen area smaller than your "virtual" circular world, provided that the virtual world's width and height are evenly divisible by your offscreen area's width and height. Many of the limitations it had before are now gone.
• Modified SWMarkSpriteForRemoval so it now moves the Sprite into a special layer in the SpriteWorld designated just for Sprites that need to be erased and removed. This means that the Sprites are removed immediately as far as your program is concerned, and the name of the function was changed back to SWRemoveSpriteFromAnimation to indicate this. You now no longer need to check each Sprite's spriteRemoval field to see if it has been marked for removal, since you will no longer encounter any Sprites that need removing after you remove it with SWRemoveSpriteFromAnimation.
HOWEVER, there is a new limitation imposed by this system; if you are removing a Sprite while in a MoveProc, FrameProc, or CollideProc, the Sprite must either be the source Sprite that was passed to that function, or it must be a Sprite in a different Layer as the source Sprite. In the case of a CollideProc, you may remove both Sprites only if they are in separate Layers. Otherwise, you may only remove one of the Sprites from within the CollideProc. In other words, SWRemoveSpriteFromAnimation has the same requirements as SWRemoveSprite. It just does the cleanup for you.
• The names of the SWGameUtils.c functions HideMenuBar and ShowMenuBar were changed to SWHideMenuBar and SWShowMenuBar, so they don't conflict with the System 8.5 functions of the same name. Additionally, it was discovered that since SWShowMenuBar disposes of the region returned to you when you call SWHideMenuBar, you should *not* dispose this region as was previously instructed. It will be disposed for you by SWShowMenuBar. If you dispose it yourself, it could cause a crash when SWShowMenuBar attempts to dispose it.
• Sped up the scaling blitters by pre-computing the scaling info and reusing it for each line. While this sped everything up by a small amount, it also allowed me to make more dramatic optimizations for the following operations:
- Direct-to-screen scaling.
- Clipped scaled sprites.
- Shrunk sprites.
• It is now highly recommended that you check the value returned by SWStickyError just before starting your animation, and also during the animation. This will help you catch error codes that you don't check for, such as the error codes returned by the various SWSetDrawProc functions. All of the demos now check SWStickyError.
• It is also recommended that you make use of the new SWSetCleanUpSpriteWorld function, documented in Inside SpriteWorld. This will ensure that if an assertion failure or FatalError() gets triggered and you had previously called SWSyncSpriteWorldToVBL with a value of true, the VBL task will be removed before the error causes your program to quit, ensuring that the machine doesn't lock up. Previously the computer would lock up if an error occurred after the SpriteWorld had been set to sync to the VBL.
• Moved Sounds.c and Sounds.h from Shark Attack into the SpriteWorld Sources -> Utils folder, and renamed them SWSounds.c and SWSounds.h. They are now "official" SpriteWorld Util files. They are intended to be simple and easy to use. Docs are in the Documentation -> Add-On Docs folder. Also cleaned up the package to make it more user-friendly and added a few new features, like volume and stereo location control. Shark Attack now plays its sounds in stereo!
• Removed the PartialMaskDrawProcs in BlitPixieScaled.c and BlitPixieRotated.c, since they were the same as the standard scaled or rotated MaskDrawProcs. If you previously used one of those PartialMaskDrawProcs, you should switch over to the equivalent scaled MaskDrawProc.
• SWDisposeFrame, SWDisposeWindowFrame, SWDisposeSprite, SWDisposeSpriteLayer, and SWDisposeSpriteWorld now require the address of the pointer you pass to them (not just the pointer itself), so they can set it to NULL. This means that SWDisposeFrame(theFrameP) needs to be changed to SWDisposeFrame(&theFrame), SWDisposeSprite(theSpriteP) becomes SWDisposeSprite(&theSpriteP), etc.
• Modified SWIsPointInSprite so it will not detect that the point is in the Sprite if the point.v is equal to the Sprite's destFrameRect.bottom or the point.h is equal to the Sprite's destFrameRect.right. Previously, a collision would be detected if this were the case, which is incorrect, since the bottom and right side of the Sprite's destFrameRect (or any Rect for that matter) are actually one pixel outside of the actual Sprite image.
• It was discovered that Brian's Translucency blitters do not mix with idle Sprites. Unfortunately, there is no way to fix this problem internally. This means that if you use translucency, you should install a MoveProc or FrameProc that is called every frame and sets the Sprite's needsToBeDrawn flag to true.
• Added tileLayer parameters to the GetTileBrightnessLevel and SetTileBrightnessLevel functions in Brian's Utils' SWTinting.c.
• SWSetCurrentFrame now returns an error code if the specified Frame is not part of the Sprite.
• Greatly improved the accuracy of the FPS report of all the demos.
• Think C projects are no longer supported, since I no longer have a 68k Mac to test them on. (Think C crashes on PowerMacs.) All projects should run except Shark Attack. To get Shark Attack's Think C project to compile, remove Sounds.c and add SWSounds.c.
New Functions:
• Added SWChangeTileSize, which allows you to change the size of your tiles without having to call SWExitTiling and SWInitTiling, which would dispose of all of your tiles. Could be useful for things such as switching between a map screen and your game screen, where the map screen uses a different size of tile than the game screen.
• Added several new functions to SWFastLine.c for drawing and copying lines and framed rects in both scrolling and non-scrolling worlds. Also changed the function previously named SWDrawLine to SWDrawLine68kAsm. See the Add-On Docs folder for more information.
• Added assertions to SpriteWorld. Now if you forget to do something important (such as locking the SpriteWorld before running the animation), you will most likely get a dialog box reporting the problem instead of having the program crash (Good idea, no? :-), provided you have the required ALRT and DITL resources. You can, of course, turn assertions off for the final build of your program if you wish, since it may run slightly faster, and since your final build should be free of the bugs that would cause assertion failures. See the section covering Assertions in Inside SpriteWorld for more information. (Just do a search for "Assertions" to find it.)
• Added SWPauseSpriteLayer and SWUnpauseSpriteLayer.
• Added SWDisposeAllSpritesInLayer (both removes and disposes the Sprites).
• Added SWCountNumSpritesInLayer.
• Added SWCloneSpriteFromTile. (Docs are in Inside SpriteWorld.)
Bug Fixes:
• Fixed several nasty bugs in Brian's BlitPixieScaled.c file:
1) Fixed a problem where the BlitPixieScaledRectDrawProcs would not draw the image properly if it were shrunk vertically.
2) Fixed a problem with all the scaling DrawProcs where they would not only draw the image incorrectly if it were clipped, but also usually crash. Since this problem has been fixed, Brian's scaling blitters may now be used in a scrolling SpriteWorld without any problems.
3) Fixed the problem of random artifacts around the right and bottom sides of a scaled Sprite.
4) Fixed a bug where SWSetSpriteScaledSize would have no effect if the Sprite had only one frame.
Some of the scaling DrawProc names have changed. However, this shouldn't affect you as a user, since SWSetSpriteScaledSize sets the DrawProc for you automatically. If you previously used any of the DrawProc names directly, look at the beginning of BlitPixieScaled.c for the new names.
• Fixed a bug in SWTranslucentBlitters.c where a crash could occur when a 16-bit Sprite was clipped. In addition, SWDispose16BitTranslucencyTable now works properly, and SWCreate16BitTranslucencyTable now returns an error code. Make sure to check the error code if you use this function.
• Fixed a bug in SWUpdateFrameMasks where the region mask would sometimes not get updated properly.
• Fixed SWDrawTile so it now changes the tileMap even if the row and column of the tile that was changed is not visible in the current visScrollRect.
• Improved the logic in SWCheckSpriteWithTiles so that it now detects collisions with tiles that your Sprite may have previous "jumped" over if it was moving so fast that it went completely over a tile in a single frame. It now doesn't matter how fast your sprite moves; even if it's going 500 pixels per frame, any tile (even a small one, such as 10x10) will still be detected if the Sprite moves over it. Also improved the search so that when the fixPosition parameter is true, the first tile checked is the one just in front of the sprite's current position, not the one it's sitting on. So if the right side of your sprite is on column 25, and your tiles are 50x50, and you move the sprite to the right and check for tiles with kSWRightSide as your searchType, the first tile checked will be column 1 (pixel column 50), not tile 0 (the one the right side was already in.)
